Copyright ã1995 by NeXT Computer, Inc.  All Rights Reserved.

NS_DEV_DOCFOR:objc_class:PrintInfo;,PrintInfo

Inherits From:	Object

Declared In:	appkit/PrintInfo.h

Class Description

A PrintInfo object stores information that's used during printing.  The Application object automatically creates a PrintInfo object that, by default, is used for all printing jobs (for that application).  You can create any number of additional PrintInfo objects; however, only one can be ªactiveº at a time, as set through Application's setPrintInfo: method.  The currently active PrintInfo object is returned through Application's printInfo method.  

Although you can set a PrintInfo's attributes through the methods it provides, this is usually the task of other objects, notably the PageLayout and PrintPanel objects.  The View or Window that's being printed may also supercede some PrintInfo settings.  In particular, a View or Window can supply the range of pages in the document and can provide its own pagination mechanism through the knowsPagesFirst:last: and getRect:forPage: methods (see the documentation of these methods in the View class for details).  

If the printed View or Window doesn't supply a pagination, the PrintInfo's vertical and horizontal pagination constants are used to trigger built-in pagination mechanisms:

Pagination Constant	Meaning

NX_AUTOPAGINATION 	The image is diced into equal-sized rectangles and placed in one column of  pages.

NX_FITPAGINATION 	The image is scaled to produce one column (horizontal) or one row (vertical) of pages.

NX_CLIPPAGINATION	The image is clipped to produce one column or row of pages. 

Vertical and horizontal pagination needn't be the same.  However, if either dimension is scaled (NX_FITPAGINATION), the other dimension is scaled by the same amount to avoid stretching the image.  If both dimensions are scaled, the scaling factor that produces the smallest image is used.  Note that PrintInfo's scaling factor (as set through setScalingFactor:) is independent of the scaling that's imposed by pagination and is applied after the document has been paginated.

The PrintInfo attributes that describe a size on a sheet of paper (the margins and the size of the paper rectangle) are in points, where 72 points equals one inch.  

Page numbers (firstPage, lastPage, and so on) are as they appear in the document.  For example, to print the first three pages of a document that contains pages numbered from 20 to 29, firstPage would be set to 20 and lastPage to 22.

Instance Variables

char *paperType;

NXRect paperRect;

NXCoord leftPageMargin;

NXCoord rightPageMargin;

NXCoord topPageMargin;

NXCoord bottomPageMargin;

float scalingFactor;

char pageOrder;

struct _pInfoFlags {
	unsigned int  orientation:1;
	unsigned int  horizCentered:1;
	unsigned int  vertCentered:1;
	unsigned int  allPages:1;
	unsigned int  horizPagination:2;
	unsigned int  vertPagination:2;
	unsigned int   printerIsOld:1;
	unsigned int   reversePageOrder:1;

} pInfoFlags;

int firstPage;

int lastPage;

int currentPage;

int copies;

char *outputFile;

DPSContext context;

short pagesPerSheet;

NXPrinter *printerObject;

id jobFeaturesTable;

const char *paperFeed;

paperType 	Type of paper.

paperRect 	Rectangle representing the paper's area.  

leftPageMargin 	Size of the left margin in points.

rightPageMargin 	Size of the right margin in points.

topPageMargin 	Size of the top margin in points.

bottomPageMargin 	Size of the bottom margin in points.

scalingFactor 	Factor to scale image by.

pageOrder 	Order of pages in document.

pInfoFlags.orientation 	Landscape or portrait mode.

pInfoFlags.horizCentered 	True if the image is centered horizontally on the page.

pInfoFlags.vertCentered 	True if the image is centered vertically on the page.

pInfoFlags.allPages 	True if all the pages are to be printed.

pInfoFlags.horizPagination 	Horizontal pagination mode.

pInfoFlags.vertPagination 	Vertical pagination mode.

firstPage 	Page number of the first page to print.

lastPage 	Page number of the last page to print.

currentPage 	Page number of the page currently being printed.

copies 	Number of copies to print.

outputFile 	File to spool to.

context 	Spooling context.

pagesPerSheet 	The number of pages per sheet of paper.

printerObject	The printer that the printing job will run on.

jobFeaturesTable	Table of additional printing job attributes.

paperFeed	Paper feed slot name.

Method Types

Initializing and freeing a PrintInfo instance
- init 
- free 

Defining the printing rectangle	- setMarginLeft:right:top:bottom: 
- getMarginLeft:right:top:bottom: 
- setOrientation:andAdjust: 
- orientation
- setPaperRect:andAdjust: 
- paperRect
- setPaperType:andAdjust:
- paperType

Page range	- setFirstPage: 
- firstPage
- setLastPage:
- lastPage
- setAllPages: 
- isAllPages
- currentPage

Pagination and scaling	- setHorizPagination: 
- horizPagination
- setVertPagination: 
- vertPagination
- setScalingFactor: 
- scalingFactor

Positioning the image on the page
- setHorizCentered: 
- isHorizCentered
- setVertCentered:
- isVertCentered
- setPagesPerSheet: 
- pagesPerSheet

Print job attributes	- initializeJobDefaults
- setJobFeature:toValue:
- valueForJobFeature:
- removeJobFeature:
- jobFeatures
- setPageOrder: 
- pageOrder
- setReversePageOrder:
- reversePageOrder
- setCopies: 
- copies
- setPaperFeed: 
- paperFeed

Specifying the printer	+ setDefaultPrinter:
+ getDefaultPrinter
- setPrinter: 
- printer

Spooling	- setOutputFile:
- outputFile
- setContext: 
- context

Archiving	- read: 
- write:

Class Methods

NS_DEV_DOCFOR:objc_method:[PrintInfo-getDefaultPrinter];,getDefaultPrinter

+ (NXPrinter *)getDefaultPrinter

Returns an NXPrinter object that corresponds to the user's default printer, as declared in the defaults database.  If the printer can't be found, nil is returned.  

See also:  + setDefaultPrinter:, - setPrinter:, - printer

NS_DEV_DOCFOR:objc_method:[PrintInfo-setDefaultPrinter:];,setDefaultPrinter:

+ setDefaultPrinter:(NXPrinter *)printer

Sets the user's default printer by writing the name and host of printer to the defaults database.  Unless a PrintInfo's printer is otherwise set (through setPrinter:) the default printer is used for printing.

See also:  + getDefaultPrinter, - setPrinter:, - printer

Instance Methods

NS_DEV_DOCFOR:objc_method:[PrintInfo-context];,context

- (DPSContext)context

Returns the Display PostScript context used for printing.

NS_DEV_DOCFOR:objc_method:[PrintInfo-copies];,copies

- (int)copies

Returns the number of copies that will be printed.

NS_DEV_DOCFOR:objc_method:[PrintInfo-currentPage];,currentPage

- (int)currentPage

Returns the page number of the page currently being printed.  This method is valid only while printing or faxing.

NS_DEV_DOCFOR:objc_method:[PrintInfo-firstPage];,firstPage

- (int)firstPage

Returns the page number of the first page that will be printed, as set through setFirstPage:, or MININT if the value hasn't been explicitly set.  If all pages are being printed, the first page value is ignored during printing.  If the page order is reversed, this value gives the page number of the last page that will be printed.  

See also:  - setFirstPage:, - setAllPages:, - setPageOrder:

NS_DEV_DOCFOR:objc_method:[PrintInfo-free];,free

- free

Frees the PrintInfo object.

NS_DEV_DOCFOR:objc_method:[PrintInfo-getMarginLeft:right:top:bottom:];,getMarginLeft:right:top:bottom:

- getMarginLeft:(NXCoord *)leftMargin
right:(NXCoord *)rightMargin
top:(NXCoord *)topMargin
bottom:(NXCoord *)bottomMargin

Returns, by reference, the sizes of the four page margins measured in points.

See also:  - setMarginLeft:right:top:bottom:

NS_DEV_DOCFOR:objc_method:[PrintInfo-horizPagination];,horizPagination

- (int)horizPagination

Returns a constant that represents the manner in which an image is distributed horizontally among pages.  See the class description, above, for a description of the pagination constants.

See also:  - setHorizPagination:

NS_DEV_DOCFOR:objc_method:[PrintInfo-init];,init

- init

Initializes the PrintInfo object after memory for it has been allocated through alloc or allocFromZone:.  Returns self.

NS_DEV_DOCFOR:objc_method:[PrintInfo-initializeJobDefaults];,initializeJobDefaults

- initializeJobDefaults

Called before each print job (specifically, before the Print panel is displayed), this method initializes the following PrintInfo attributes:

Attribute	Value

First page	MININT
Last page	MAXINT
Copies	1
Page order	First-to-last
Printer	The user's default printer
Paper feed	The default paper feed slot

NS_DEV_DOCFOR:objc_method:[PrintInfo-isAllPages];,isAllPages

- (BOOL)isAllPages

Returns whether all pages will be printed.  If NO, only those pages that fall within [firstPage, lastPage] will be printed.

See also:  - setAllPages:

NS_DEV_DOCFOR:objc_method:[PrintInfo-isHorizCentered];,isHorizCentered

- (BOOL)isHorizCentered

Returns whether the image is centered horizontally on a page; if this returns NO, the image is flush against the left margin.  If the image spills over more than one page horizontally, this value is ignored and the image is always set against the left margin.

NS_DEV_DOCFOR:objc_method:[PrintInfo-isVertCentered];,isVertCentered

- (BOOL)isVertCentered

Returns whether the image is centered vertically on a page; if this returns NO, the image is flush against the top margin.  If the image spills over more than one page vertically, then this value is ignored and the image is always set against the top margin.

See also:  - setVertCentered:

NS_DEV_DOCFOR:objc_method:[PrintInfo-jobFeatures];,jobFeatures

- (const char **)jobFeatures

Returns a pointer to an array of pointers that contains the keys to the job features table, the hash table that contains additional printing-job attributes.  You would use these keys as arguments to methods such as valueForJobFeature: and removeJobFeature:.  It's the caller's responsibility to free the pointer to the array, but not the pointers in the array.

See also:  - setJobFeature:toValue:, - valueForJobFeature:, - removeJobFeature:

NS_DEV_DOCFOR:objc_method:[PrintInfo-lastPage];,lastPage

- (int)lastPage

Returns the page number of the last page that will be printed, as set through setLastPage:, or MAXINT if the value hasn't been explicitly set.  If all pages are being printed, the last page value is ignored during printing.  If the page order is reversed, this value gives the page number of the first page that will be printed.  

See also:  - setLastPage:, - setAllPages:, - setReversePageOrder:

NS_DEV_DOCFOR:objc_method:[PrintInfo-orientation];,orientation

- (char)orientation

Returns the page orientation as NX_PORTRAIT or NX_LANDSCAPE.

See also:  - setOrientation:andAdjust:, - setPaperType:andAdjust:, - setPaperRect:andAdjust:

NS_DEV_DOCFOR:objc_method:[PrintInfo-outputFile];,outputFile

- (const char *)outputFile

Returns the name of the file to which the generated PostScript code is sent.  If this is NULL, the code is written to a temporary file.

See also:  - setOutputFile:

NS_DEV_DOCFOR:objc_method:[PrintInfo-pageOrder];,pageOrder

- (char)pageOrder

Returns a constant that denotes the order in which pages are printed.  See setPageOrder: for the page order constants.

See also:  - setPageOrder:

NS_DEV_DOCFOR:objc_method:[PrintInfo-pagesPerSheet];,pagesPerSheet

- (short)pagesPerSheet

Returns the number of pages per sheet of paper.

NS_DEV_DOCFOR:objc_method:[PrintInfo-paperFeed];,paperFeed

- (const char *)paperFeed

Returns the name of the currently used paper feed slot.  

See also:  - setPaperFeed:

NS_DEV_DOCFOR:objc_method:[PrintInfo-paperRect];,paperRect

- (const NXRect *)paperRect

Returns a pointer to a rectangle that gives the size of the paper, measured in points.  Note that the rectangle is useful only for its size field; the origin of the paper is always (0.0, 0.0).

NS_DEV_DOCFOR:objc_method:[PrintInfo-paperType];,paperType

- (const char *)paperType

Returns the paper type.  If the type is unknown, an empty string is returned.

NS_DEV_DOCFOR:objc_method:[PrintInfo-printer];,printer

- (NXPrinter *)printer

Returns the NXPrinter that's used for printing.

NS_DEV_DOCFOR:objc_method:[PrintInfo-read:];,read:

- read:(NXTypedStream *)stream

Reads the PrintInfo from the typed stream stream.

NS_DEV_DOCFOR:objc_method:[PrintInfo-removeJobFeature:];,removeJobFeature:

- removeJobFeature:(const char *)key

Removes, from the job-features hash table, the element that corresponds to key.

See also:  - jobFeatures, - setJobFeature:toValue:, - valueForJobFeature:

NS_DEV_DOCFOR:objc_method:[PrintInfo-reversePageOrder];,reversePageOrder

- (BOOL)reversePageOrder

Returns YES if the PrintInfo dictates that pages will be printed in reverse order (in other words, if the ordering established through setPageOrder: is reversed). 

See also:  - setReversePageOrder:, - setPageOrder:

NS_DEV_DOCFOR:objc_method:[PrintInfo-scalingFactor];,scalingFactor

- (float)scalingFactor

Returns the factor by which the image is scaled.

NS_DEV_DOCFOR:objc_method:[PrintInfo-setAllPages:];,setAllPages:

- setAllPages:(BOOL)flag

Sets whether all the pages of the document are to be printed (as opposed to a subset given by the firstPage and lastPage values).

NS_DEV_DOCFOR:objc_method:[PrintInfo-setContext:];,setContext:

- setContext:(DPSContext)aContext

Sets the Display PostScript context used for printing.  This is normally done by the printing machinery in View.

NS_DEV_DOCFOR:objc_method:[PrintInfo-setCopies:];,setCopies:

- setCopies:(int)anInt

Sets the number of copies that will be printed.

NS_DEV_DOCFOR:objc_method:[PrintInfo-setFirstPage:];,setFirstPage:

- setFirstPage:(int)anInt

Sets the page number of the first page that will be printed.

NS_DEV_DOCFOR:objc_method:[PrintInfo-setHorizCentered:];,setHorizCentered:

- setHorizCentered:(BOOL)flag

Sets whether the image is centered horizontally on a page; if flag is NO, the image is flush against the left margin.  If the image spills over more than one page horizontally, then flag is ignored and the image is always against the left margin.

NS_DEV_DOCFOR:objc_method:[PrintInfo-setHorizPagination:];,setHorizPagination:

- setHorizPagination:(int)mode

Sets the way in which a document is divided horizontally into pages.  See the class description, above, for the pagination constants that you can use as the argument to this method.

NS_DEV_DOCFOR:objc_method:[PrintInfo-setJobFeature:toValue:];,setJobFeature:toValue:

- setJobFeature:(const char *)feature toValue:(const char *)value

Sets the value of the given job feature.  The feature is added to the job-features hash table if it isn't already present.

NS_DEV_DOCFOR:objc_method:[PrintInfo-setLastPage:];,setLastPage:

- setLastPage:(int)anInt

Sets the page number of the last page that will be printed.  

NS_DEV_DOCFOR:objc_method:[PrintInfo-setMarginLeft:right:top:bottom:];,setMarginLeft:right:top:bottom:

- setMarginLeft:(NXCoord)leftMargin
right:(NXCoord)rightMargin
top:(NXCoord)topMargin
bottom:(NXCoord)bottomMargin

Sets the margins.  All margins are in points.

NS_DEV_DOCFOR:objc_method:[PrintInfo-setOrientation:andAdjust:];,setOrientation:andAdjust:

- setOrientation:(char)mode andAdjust:(BOOL)flag

Sets the orientation or the page;  mode should be either NX_PORTRAIT or NX_LANDSCAPE.

If flag is NO, then only the orientation is affected.  If flag is YES, the paper rectangle value is updated to reflect the new orientation.

NS_DEV_DOCFOR:objc_method:[PrintInfo-setOutputFile:];,setOutputFile:

- setOutputFile:(const char *)aString

Sets the name of the file to which the generated PostScript code is sent.  If aString is NULL, the code is sent to a temporary file.

NS_DEV_DOCFOR:objc_method:[PrintInfo-setPageOrder:];,setPageOrder:

- setPageOrder:(char)mode

Sets the order in which pages are printed as one of these constants:

NX_DESCENDINGORDER
NX_SPECIALORDER
NX_ASCENDINGORDER
NX_UNKNOWNORDER

See also:  - reversePageOrder, - pageOrder

NS_DEV_DOCFOR:objc_method:[PrintInfo-setPagesPerSheet:];,setPagesPerSheet:

- setPagesPerSheet:(short)pageCount

Sets the number of pages of the document that are printed on a single sheet of paper.  This number is rounded up to a power of two when used by the system.

NS_DEV_DOCFOR:objc_method:[PrintInfo-setPaperFeed:];,setPaperFeed:

- setPaperFeed:(const char *)paperFeedSlot

Sets the paper feed slot by name.  If paperFeedSlot is NULL (or an empty string), any paper feed slot is acceptable; to choose the manual feed slot, set the name to ªNXManualº.  Any other name that you use must appear in the PPD table (as documented in the NXPrinter class).  Returns self.  

See also:  - setPaperFeed:

NS_DEV_DOCFOR:objc_method:[PrintInfo-setPaperRect:andAdjust:];,setPaperRect:andAdjust:

- setPaperRect:(const NXRect *)aRect andAdjust:(BOOL)flag

Sets the size of the paper, measured in points, that's to be used in printing.  The origin of the rectangle is always set to (0,0)Ðthe origin field of aRect is ignored.  

If flag is NO, then only the paper rectangle is changed.  If flag is YES, the orientation and paper type values are updated to reflect the new size.

NS_DEV_DOCFOR:objc_method:[PrintInfo-setPaperType:andAdjust:];,setPaperType:andAdjust:

- setPaperType:(const char *)type andAdjust:(BOOL)flag

Sets the name of the paper type. 

If flag is NO, only the paper type is changed.  If flag is YES, the paper rectangle and orientation values are updated to reflect the new type (given that type is a recognized paper type).

NS_DEV_DOCFOR:objc_method:[PrintInfo-setPrinter:];,setPrinter:

- setPrinter:(NXPrinter *)aPrinter

Sets the printer that's used in subsequent printing jobs.

NS_DEV_DOCFOR:objc_method:[PrintInfo-setReversePageOrder:];,setReversePageOrder:

- setReversePageOrder:(BOOL)flag

Sets whether pages are printed in reverse order.  This ordering is applied to the page order mode set through setPageOrder:.  Returns self.

See also:  - reversePageOrder, - setPageOrder:

NS_DEV_DOCFOR:objc_method:[PrintInfo-setScalingFactor:];,setScalingFactor:

- setScalingFactor:(float)aFloat

Sets the amount by which the document is scaled.  Note that the scaling you set has no effect if the document does its own pagination through View's knowsPagesFirst:last: method.

NS_DEV_DOCFOR:objc_method:[PrintInfo-setVertCentered:];,setVertCentered:

- setVertCentered:(BOOL)flag

Sets whether the default implementation of placePrintRect:offset: in the View class centers the image vertically on the page.

NS_DEV_DOCFOR:objc_method:[PrintInfo-setVertPagination:];,setVertPagination:

- setVertPagination:(int)mode

Sets the way in which a document is divided vertically into pages.  See the class description, above, for the pagination constants that you can use as the argument to this method.

NS_DEV_DOCFOR:objc_method:[PrintInfo-valueForJobFeature:];,valueForJobFeature:

- (const char *)valueForJobFeature:(const char *)feature

Returns the value for the given printing feature, as stored in the job-features table.

See also:  - jobFeatures, - setJobFeature:toValue:, - removeJobFeature

NS_DEV_DOCFOR:objc_method:[PrintInfo-vertPagination];,vertPagination

- (int)vertPagination

Returns a constant that represents the manner in which an image is distributed vertically among pages.  See the class description, above, for a description of the pagination constants.

See also:  - setVertPagination:

NS_DEV_DOCFOR:objc_method:[PrintInfo-write:];,write:

- write:(NXTypedStream *)stream

Writes the PrintInfo to the typed stream stream.